// ASM: a very small and fast Java bytecode manipulation framework
// Copyright (c) 2000-2011 INRIA, France Telecom
// All rights reserved.
//
// Redistribution and use in source and binary forms, with or without
// modification, are permitted provided that the following conditions
// are met:
// 1. Redistributions of source code must retain the above copyright
//    notice, this list of conditions and the following disclaimer.
// 2. Redistributions in binary form must reproduce the above copyright
//    notice, this list of conditions and the following disclaimer in the
//    documentation and/or other materials provided with the distribution.
// 3. Neither the name of the copyright holders nor the names of its
//    contributors may be used to endorse or promote products derived from
//    this software without specific prior written permission.
//
// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
// AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
// ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
// LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
// CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
// SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
// INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
// CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
// ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF
// THE POSSIBILITY OF SUCH DAMAGE.

package org.objectweb.asm;

/**
 * A reference to a type appearing in a class, field or method declaration, or on an instruction. Such a reference designates the part of the class where the referenced type is appearing (e.g. an 'extends', 'implements' or 'throws' clause, a 'new' instruction, a 'catch' clause, a type cast, a local variable declaration, etc).
 *
 * @author Eric Bruneton
 */
public class TypeReference {

	/**
	 * The sort of type references that target a type parameter of a generic class. See {@link #getSort}.
	 */
	public static final int CLASS_TYPE_PARAMETER = 0x00;

	/**
	 * The sort of type references that target a type parameter of a generic method. See {@link #getSort}.
	 */
	public static final int METHOD_TYPE_PARAMETER = 0x01;

	/**
	 * The sort of type references that target the super class of a class or one of the interfaces it implements. See {@link #getSort}.
	 */
	public static final int CLASS_EXTENDS = 0x10;

	/**
	 * The sort of type references that target a bound of a type parameter of a generic class. See {@link #getSort}.
	 */
	public static final int CLASS_TYPE_PARAMETER_BOUND = 0x11;

	/**
	 * The sort of type references that target a bound of a type parameter of a generic method. See {@link #getSort}.
	 */
	public static final int METHOD_TYPE_PARAMETER_BOUND = 0x12;

	/** The sort of type references that target the type of a field. See {@link #getSort}. */
	public static final int FIELD = 0x13;

	/** The sort of type references that target the return type of a method. See {@link #getSort}. */
	public static final int METHOD_RETURN = 0x14;

	/**
	 * The sort of type references that target the receiver type of a method. See {@link #getSort}.
	 */
	public static final int METHOD_RECEIVER = 0x15;

	/**
	 * The sort of type references that target the type of a formal parameter of a method. See {@link #getSort}.
	 */
	public static final int METHOD_FORMAL_PARAMETER = 0x16;

	/**
	 * The sort of type references that target the type of an exception declared in the throws clause of a method. See {@link #getSort}.
	 */
	public static final int THROWS = 0x17;

	/**
	 * The sort of type references that target the type of a local variable in a method. See {@link #getSort}.
	 */
	public static final int LOCAL_VARIABLE = 0x40;

	/**
	 * The sort of type references that target the type of a resource variable in a method. See {@link #getSort}.
	 */
	public static final int RESOURCE_VARIABLE = 0x41;

	/**
	 * The sort of type references that target the type of the exception of a 'catch' clause in a method. See {@link #getSort}.
	 */
	public static final int EXCEPTION_PARAMETER = 0x42;

	/**
	 * The sort of type references that target the type declared in an 'instanceof' instruction. See {@link #getSort}.
	 */
	public static final int INSTANCEOF = 0x43;

	/**
	 * The sort of type references that target the type of the object created by a 'new' instruction. See {@link #getSort}.
	 */
	public static final int NEW = 0x44;

	/**
	 * The sort of type references that target the receiver type of a constructor reference. See {@link #getSort}.
	 */
	public static final int CONSTRUCTOR_REFERENCE = 0x45;

	/**
	 * The sort of type references that target the receiver type of a method reference. See {@link #getSort}.
	 */
	public static final int METHOD_REFERENCE = 0x46;

	/**
	 * The sort of type references that target the type declared in an explicit or implicit cast instruction. See {@link #getSort}.
	 */
	public static final int CAST = 0x47;

	/**
	 * The sort of type references that target a type parameter of a generic constructor in a constructor call. See {@link #getSort}.
	 */
	public static final int CONSTRUCTOR_INVOCATION_TYPE_ARGUMENT = 0x48;

	/**
	 * The sort of type references that target a type parameter of a generic method in a method call. See {@link #getSort}.
	 */
	public static final int METHOD_INVOCATION_TYPE_ARGUMENT = 0x49;

	/**
	 * The sort of type references that target a type parameter of a generic constructor in a constructor reference. See {@link #getSort}.
	 */
	public static final int CONSTRUCTOR_REFERENCE_TYPE_ARGUMENT = 0x4A;

	/**
	 * The sort of type references that target a type parameter of a generic method in a method reference. See {@link #getSort}.
	 */
	public static final int METHOD_REFERENCE_TYPE_ARGUMENT = 0x4B;

	/**
	 * The target_type and target_info structures - as defined in the Java Virtual Machine Specification (JVMS) - corresponding to this type reference. target_type uses one byte, and all the target_info union fields use up to 3 bytes (except localvar_target, handled with the specific method {@link MethodVisitor#visitLocalVariableAnnotation}). Thus, both structures can be stored in an int.
	 *
	 * <p>
	 * This int field stores target_type (called the TypeReference 'sort' in the public API of this class) in its most significant byte, followed by the target_info fields. Depending on target_type, 1, 2 or even 3 least significant bytes of this field are unused. target_info fields which reference bytecode offsets are set to 0 (these offsets are ignored in ClassReader, and recomputed in MethodWriter).
	 *
	 * @see <a href="https://docs.oracle.com/javase/specs/jvms/se9/html/jvms-4.html#jvms-4.7.20">JVMS 4.7.20</a>
	 * @see <a href="https://docs.oracle.com/javase/specs/jvms/se9/html/jvms-4.html#jvms-4.7.20.1">JVMS 4.7.20.1</a>
	 */
	private final int targetTypeAndInfo;

	/**
	 * Constructs a new TypeReference.
	 *
	 * @param typeRef
	 *          the int encoded value of the type reference, as received in a visit method related to type annotations, such as {@link ClassVisitor#visitTypeAnnotation}.
	 */
	public TypeReference(final int typeRef) {
		this.targetTypeAndInfo = typeRef;
	}

	/**
	 * Returns a type reference of the given sort.
	 *
	 * @param sort
	 *          one of {@link #FIELD}, {@link #METHOD_RETURN}, {@link #METHOD_RECEIVER}, {@link #LOCAL_VARIABLE}, {@link #RESOURCE_VARIABLE}, {@link #INSTANCEOF}, {@link #NEW}, {@link #CONSTRUCTOR_REFERENCE}, or {@link #METHOD_REFERENCE}.
	 * @return a type reference of the given sort.
	 */
	public static TypeReference newTypeReference(final int sort) {
		return new TypeReference(sort << 24);
	}

	/**
	 * Returns a reference to a type parameter of a generic class or method.
	 *
	 * @param sort
	 *          one of {@link #CLASS_TYPE_PARAMETER} or {@link #METHOD_TYPE_PARAMETER}.
	 * @param paramIndex
	 *          the type parameter index.
	 * @return a reference to the given generic class or method type parameter.
	 */
	public static TypeReference newTypeParameterReference(final int sort, final int paramIndex) {
		return new TypeReference((sort << 24) | (paramIndex << 16));
	}

	/**
	 * Returns a reference to a type parameter bound of a generic class or method.
	 *
	 * @param sort
	 *          one of {@link #CLASS_TYPE_PARAMETER} or {@link #METHOD_TYPE_PARAMETER}.
	 * @param paramIndex
	 *          the type parameter index.
	 * @param boundIndex
	 *          the type bound index within the above type parameters.
	 * @return a reference to the given generic class or method type parameter bound.
	 */
	public static TypeReference newTypeParameterBoundReference(final int sort, final int paramIndex,
			final int boundIndex) {
		return new TypeReference((sort << 24) | (paramIndex << 16) | (boundIndex << 8));
	}

	/**
	 * Returns a reference to the super class or to an interface of the 'implements' clause of a class.
	 *
	 * @param itfIndex
	 *          the index of an interface in the 'implements' clause of a class, or -1 to reference the super class of the class.
	 * @return a reference to the given super type of a class.
	 */
	public static TypeReference newSuperTypeReference(final int itfIndex) {
		return new TypeReference((CLASS_EXTENDS << 24) | ((itfIndex & 0xFFFF) << 8));
	}

	/**
	 * Returns a reference to the type of a formal parameter of a method.
	 *
	 * @param paramIndex
	 *          the formal parameter index.
	 * @return a reference to the type of the given method formal parameter.
	 */
	public static TypeReference newFormalParameterReference(final int paramIndex) {
		return new TypeReference((METHOD_FORMAL_PARAMETER << 24) | (paramIndex << 16));
	}

	/**
	 * Returns a reference to the type of an exception, in a 'throws' clause of a method.
	 *
	 * @param exceptionIndex
	 *          the index of an exception in a 'throws' clause of a method.
	 * @return a reference to the type of the given exception.
	 */
	public static TypeReference newExceptionReference(final int exceptionIndex) {
		return new TypeReference((THROWS << 24) | (exceptionIndex << 8));
	}

	/**
	 * Returns a reference to the type of the exception declared in a 'catch' clause of a method.
	 *
	 * @param tryCatchBlockIndex
	 *          the index of a try catch block (using the order in which they are visited with visitTryCatchBlock).
	 * @return a reference to the type of the given exception.
	 */
	public static TypeReference newTryCatchReference(final int tryCatchBlockIndex) {
		return new TypeReference((EXCEPTION_PARAMETER << 24) | (tryCatchBlockIndex << 8));
	}

	/**
	 * Returns a reference to the type of a type argument in a constructor or method call or reference.
	 *
	 * @param sort
	 *          one of {@link #CAST}, {@link #CONSTRUCTOR_INVOCATION_TYPE_ARGUMENT}, {@link #METHOD_INVOCATION_TYPE_ARGUMENT}, {@link #CONSTRUCTOR_REFERENCE_TYPE_ARGUMENT}, or {@link #METHOD_REFERENCE_TYPE_ARGUMENT}.
	 * @param argIndex
	 *          the type argument index.
	 * @return a reference to the type of the given type argument.
	 */
	public static TypeReference newTypeArgumentReference(final int sort, final int argIndex) {
		return new TypeReference((sort << 24) | argIndex);
	}

	/**
	 * Returns the sort of this type reference.
	 *
	 * @return one of {@link #CLASS_TYPE_PARAMETER}, {@link #METHOD_TYPE_PARAMETER}, {@link #CLASS_EXTENDS}, {@link #CLASS_TYPE_PARAMETER_BOUND}, {@link #METHOD_TYPE_PARAMETER_BOUND}, {@link #FIELD}, {@link #METHOD_RETURN}, {@link #METHOD_RECEIVER}, {@link #METHOD_FORMAL_PARAMETER}, {@link #THROWS}, {@link #LOCAL_VARIABLE}, {@link #RESOURCE_VARIABLE}, {@link #EXCEPTION_PARAMETER}, {@link #INSTANCEOF}, {@link #NEW}, {@link #CONSTRUCTOR_REFERENCE}, {@link #METHOD_REFERENCE}, {@link #CAST}, {@link #CONSTRUCTOR_INVOCATION_TYPE_ARGUMENT}, {@link #METHOD_INVOCATION_TYPE_ARGUMENT}, {@link #CONSTRUCTOR_REFERENCE_TYPE_ARGUMENT}, or {@link #METHOD_REFERENCE_TYPE_ARGUMENT}.
	 */
	public int getSort() {
		return targetTypeAndInfo >>> 24;
	}

	/**
	 * Returns the index of the type parameter referenced by this type reference. This method must only be used for type references whose sort is {@link #CLASS_TYPE_PARAMETER}, {@link #METHOD_TYPE_PARAMETER}, {@link #CLASS_TYPE_PARAMETER_BOUND} or {@link #METHOD_TYPE_PARAMETER_BOUND}.
	 *
	 * @return a type parameter index.
	 */
	public int getTypeParameterIndex() {
		return (targetTypeAndInfo & 0x00FF0000) >> 16;
	}

	/**
	 * Returns the index of the type parameter bound, within the type parameter {@link #getTypeParameterIndex}, referenced by this type reference. This method must only be used for type references whose sort is {@link #CLASS_TYPE_PARAMETER_BOUND} or {@link #METHOD_TYPE_PARAMETER_BOUND}.
	 *
	 * @return a type parameter bound index.
	 */
	public int getTypeParameterBoundIndex() {
		return (targetTypeAndInfo & 0x0000FF00) >> 8;
	}

	/**
	 * Returns the index of the "super type" of a class that is referenced by this type reference. This method must only be used for type references whose sort is {@link #CLASS_EXTENDS}.
	 *
	 * @return the index of an interface in the 'implements' clause of a class, or -1 if this type reference references the type of the super class.
	 */
	public int getSuperTypeIndex() {
		return (short) ((targetTypeAndInfo & 0x00FFFF00) >> 8);
	}

	/**
	 * Returns the index of the formal parameter whose type is referenced by this type reference. This method must only be used for type references whose sort is {@link #METHOD_FORMAL_PARAMETER}.
	 *
	 * @return a formal parameter index.
	 */
	public int getFormalParameterIndex() {
		return (targetTypeAndInfo & 0x00FF0000) >> 16;
	}

	/**
	 * Returns the index of the exception, in a 'throws' clause of a method, whose type is referenced by this type reference. This method must only be used for type references whose sort is {@link #THROWS}.
	 *
	 * @return the index of an exception in the 'throws' clause of a method.
	 */
	public int getExceptionIndex() {
		return (targetTypeAndInfo & 0x00FFFF00) >> 8;
	}

	/**
	 * Returns the index of the try catch block (using the order in which they are visited with visitTryCatchBlock), whose 'catch' type is referenced by this type reference. This method must only be used for type references whose sort is {@link #EXCEPTION_PARAMETER} .
	 *
	 * @return the index of an exception in the 'throws' clause of a method.
	 */
	public int getTryCatchBlockIndex() {
		return (targetTypeAndInfo & 0x00FFFF00) >> 8;
	}

	/**
	 * Returns the index of the type argument referenced by this type reference. This method must only be used for type references whose sort is {@link #CAST}, {@link #CONSTRUCTOR_INVOCATION_TYPE_ARGUMENT}, {@link #METHOD_INVOCATION_TYPE_ARGUMENT}, {@link #CONSTRUCTOR_REFERENCE_TYPE_ARGUMENT}, or {@link #METHOD_REFERENCE_TYPE_ARGUMENT}.
	 *
	 * @return a type parameter index.
	 */
	public int getTypeArgumentIndex() {
		return targetTypeAndInfo & 0xFF;
	}

	/**
	 * Returns the int encoded value of this type reference, suitable for use in visit methods related to type annotations, like visitTypeAnnotation.
	 *
	 * @return the int encoded value of this type reference.
	 */
	public int getValue() {
		return targetTypeAndInfo;
	}

	/**
	 * Puts the given target_type and target_info JVMS structures into the given ByteVector.
	 *
	 * @param targetTypeAndInfo
	 *          a target_type and a target_info structures encoded as in {@link #targetTypeAndInfo}. LOCAL_VARIABLE and RESOURCE_VARIABLE target types are not supported.
	 * @param output
	 *          where the type reference must be put.
	 */
	static void putTarget(final int targetTypeAndInfo, final ByteVector output) {
		switch (targetTypeAndInfo >>> 24) {
		case CLASS_TYPE_PARAMETER:
		case METHOD_TYPE_PARAMETER:
		case METHOD_FORMAL_PARAMETER:
			output.putShort(targetTypeAndInfo >>> 16);
			break;
		case FIELD:
		case METHOD_RETURN:
		case METHOD_RECEIVER:
			output.putByte(targetTypeAndInfo >>> 24);
			break;
		case CAST:
		case CONSTRUCTOR_INVOCATION_TYPE_ARGUMENT:
		case METHOD_INVOCATION_TYPE_ARGUMENT:
		case CONSTRUCTOR_REFERENCE_TYPE_ARGUMENT:
		case METHOD_REFERENCE_TYPE_ARGUMENT:
			output.putInt(targetTypeAndInfo);
			break;
		case CLASS_EXTENDS:
		case CLASS_TYPE_PARAMETER_BOUND:
		case METHOD_TYPE_PARAMETER_BOUND:
		case THROWS:
		case EXCEPTION_PARAMETER:
		case INSTANCEOF:
		case NEW:
		case CONSTRUCTOR_REFERENCE:
		case METHOD_REFERENCE:
			output.put12(targetTypeAndInfo >>> 24, (targetTypeAndInfo & 0xFFFF00) >> 8);
			break;
		default:
			throw new IllegalArgumentException();
		}
	}
}
